home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 November: Tool Chest / Dev.CD Nov 00 TC Disk 2.toast / pc / sample code / sound / sndplaydoublebuffer / read me - sndplaydblbuffer next >
Encoding:
Text File  |  2000-09-28  |  7.7 KB  |  179 lines
  1. /*                                Read Me for SndPlayDoubleBuffer
  2.  
  3. --New--
  4.  
  5. Now version 1.1.1
  6. Fixed IMA random access bug that caused grabage playback.
  7. Updated pause/resume code to use siRateMultiplier which is Carbon compatible,
  8. instead of using getRateCmd/rateCmd which are not Carbon compatible.
  9.  
  10. Has been updated with some bug fixes and now is a Metrowerks Pro 5 project.
  11.  
  12. --Goal of this sample--
  13.  
  14. The primary purpose of this sample code is to show developers how to use SndPlayDoubleBuffer
  15. to play AIFF, WAVE, and .au files asynchronously from disk.
  16.  
  17. To this end this sample can be used to show you how to:
  18.  
  19. 1) parse an AIFF, 'snd ' resource, WAVE, or .au header
  20. 2) use PBReadAsync() at interrupt time
  21. 3) munge AIFF, WAVE, and .au data into a form the Sound Manager can play
  22. 4) set up the sound header to play compressed and uncompressed sounds
  23. 5) instantly (well, really quickly) pause a sound
  24. 6) stop a sound so you can play from some other part of the sound
  25. 7) make it sound like you are playing a sound backwards
  26. 8) use completion routines
  27. 9) have fun with sounds
  28.  
  29.  
  30. --Features--
  31.  
  32. SimpleApp
  33.  
  34. This code was developed using fellow DTS engineer (and really cool guy) Matt Mora's SimpleApp
  35. framework.
  36.  
  37. This simple framework hides the dirty work of the Mac interface allowing me (and you) to
  38. concentrate on the code that is actually doing the interesting work.
  39.  
  40. AIFC
  41. ----
  42.  
  43. It can play AIFC files compressed with µlaw, IMA, MACE 3:1 and MACE 6:1, it should be able to
  44. play other formats if the proper decompressor is installed, but I have only tested with these
  45. four decompressors.
  46.  
  47. IMA is a run length compression, and as such you cannot play an IMA compressed sound backwards
  48. using the simple techniques I use in this example.  When doing random access in an IMA file,
  49. it is very important to always start playing at a frame boundary, because this contains the
  50. start information (basically the information that would have been generated if you played
  51. the file from the start until this frame).  Fixed a bug that was causing the file to not play
  52. at the beginning of a frame and therefore play gargbage.
  53.  
  54. AIFF
  55. ----
  56.  
  57. It can play all AIFF files (that I know of) without a problem.
  58.  
  59. 'snd ' resources
  60. ----------------
  61.  
  62. It can play all the 'snd ' resources that I have seen.  I have not done extensive testing
  63. on these yet, but they work well enough so far.  I would like to add the ability to play
  64. all the 'snd ' resources inside of a resource file, but currently it only plays the first
  65. 'snd ' resource that it finds.
  66.  
  67. It does not play 'snd ' resources that are not sampled-sound data, and it does not play
  68. 'snd ' resources that have multiple commands (i.e. multiple tracks), but I haven't seen
  69. any of these files to test with either.
  70.  
  71. Playing a 'snd ' resource isn't as easy at would seem.  Since this is a SndPlayDoubleBuffer()
  72. example I am not reading in the entire 'snd ' resource into memory as some other examples do.
  73. Since I have to fill SndPlayDoubleBuffer() buffers' at interrupt time, using the Resource
  74. Manager is out as well.  I have written some _VERY_ basic functions that will open a resource
  75. fork, read in the header, look around and get the information I need.  In this way I am able
  76. to use PBReadAsync() at interrupt time to read more of the 'snd ' resource.
  77.  
  78. If you wish to use this resource code, feel free, but make sure you test it thoroughly.  It
  79. works for me, but I can't say that it does everything, or that it does what it does, in all
  80. cases, correctly.
  81.  
  82. .snd and .au files
  83. ------------------
  84.  
  85. I have added Sun/NeXT .snd support (better known as .au sounds).  Currently it can play
  86. 8 and 16 bit linear (non-compressed) sounds and µlaw compressed files.  The other file
  87. formats don't seem to be too popular (I haven't been able to find one), and it doesn't
  88. look like the Sound Manager would support them (like 24 and 32 bit linear) even if I found
  89. them.
  90.  
  91. WAVE
  92. ----
  93.  
  94. It can play PCM (Pulse Code Modulation) and µlaw WAVE files, it can not play ADPCM or IMA
  95. compressed WAVE files.  IMA compressed WAVE files have a different data stream than an IMA
  96. compressed AIFF file and the IMA decompressor cannot handle it.  I do not think I will ever
  97. be able to make IMA compressed WAVE files play without a new IMA decompressor that can
  98. handle this different format.
  99.  
  100. The endian conversion code has been written in C and both 68K and PowerPC assembly (because
  101. I wanted to) so WAVE files will work on both 68K and PPC Macs, but they should require less
  102. interrupt resources on a Power Mac because the PPC assembly makes use of the (really cool)
  103. store byte reversed command to make the processor do all the real endian conversion.  Using
  104. this command the assembly version of the routines are about the same size, or smaller than
  105. their C versions.  I have not unrolled the PPC assembly because I didn't feel there was too
  106. much speed to be gained (though I did no actuall testing).  This is left as an exercise for
  107. the reader (I've always wanted to say that).
  108.  
  109. Note:
  110. If you do random access inside of a WAVE file you may get garbage played for an instant.
  111. I have not tracked down where this is coming from, and it doesn't happen all the time.  I'm
  112. working on finding the cause of this.
  113.  
  114.  
  115. --Background--
  116.  
  117. When I first started this sample I was hoping for something similar to MoreFiles, well that
  118. didn't happen.  But the routines in DoubleBufferFromFile.c, Private_DBFFFunctions.c,
  119. and Interrupt_Routines.c are still pretty useful.  I tried to make them as simple and self-
  120. sufficient possible.  You will find, however, that it is a somewhat complicated process to
  121. fill in the data required to start playing an AIFF, 'snd ' resource, WAVE, or .au file so
  122. those routines work more as a package, but I think it is a good start.
  123.  
  124. I hope to have made the code largely self explanitory, with comments where necessary.
  125.  
  126. As always, I welcome your feedback (good or bad).  I can be reached at mcookson@apple.com.
  127. Please let me know what you find useful, what you find not useful, and what you would like
  128. to see in a future example of this type.
  129.  
  130.  
  131. --Known bugs--
  132.  
  133. The only bug that I am aware of is the problem with the random WAVE garbage.
  134.  
  135.  
  136. --Fixed bugs--
  137.  
  138. Fixed a bug that was causing the file to not play at the beginning of a frame and therefore
  139. play gargbage in IMA compressed AIFF files.  This fix may help other sounds to play correctly
  140. when doing random access, but I have not tested that.
  141.  
  142. Fixed a bug where I wasn't adding the last partial buffer into the total number of buffers
  143. needed to play a sound.  This would make the scroll bar off by one, and if the sound only
  144. required one partially full buffer it thought there were zero buffers and the scroll bar
  145. and buttons were left in a bad state.
  146.  
  147. Figured out where the length of a WAVE file really is which fixed the problem of garbage
  148. playing at the end of WAVE file (since non-wave data can follow the sound).
  149.  
  150. Fixed a bug in the initialization code that seemed to only cause an internal consistency
  151. error on 68K Macs.
  152.  
  153.  
  154. --New features--
  155.  
  156. Added 'wav ' as a file type to look for sounds in.
  157.  
  158. Added support for Macintosh Easy Open and an 'open' resource.
  159.  
  160. Added a 'vers' resource and some file icons for the application.
  161.  
  162.  
  163. --Disclaimer--
  164.  
  165. The Sound Manager currently does not directly support WAVE or .au/.snd files like it does
  166. 'snd ' and AIFF/AIFC files.  Sound Manager 3.2 does have an endian decompressor for WAVE
  167. files, but I do not use it.  The Sound Manager does not directly read or parse .au/.snd
  168. or WAVE file's headers.  The code I have has been written based on the file format information
  169. that I have found on World Wide Web and the few files that I have been able to make or
  170. find.  This code is probably no where near complete, make sure you test it with the sounds
  171. you want to play to make sure that it works before you include this code in a real product.
  172.  
  173.  
  174. Happy coding,
  175. Mark Cookson
  176. Developer Technical Support
  177. Apple Computer, Inc.
  178.  
  179. */